home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 February / EnigmA AMIGA RUN 15 (1997)(G.R. Edizioni)(IT)[!][issue 1997-02][PLANET CD V].iso / enigma / earcd / sviluppo / svilupp2 / doorio12.rdm < prev    next >
Text File  |  1997-01-18  |  5KB  |  108 lines
  1. Short:    BBS Door In/Out (Multiport)
  2. Author:   mac@gorehost.dontpanic.sub.org (Alexander Haarer)
  3. Uploader: cybox@i-online.ohz.north.de (Stephan Schuett)
  4. Type:     dev/misc
  5.  
  6. Update 1.2
  7. Hi there.. this is the Documentation ;) for the door_io.library. 1.2
  8.  
  9. History:
  10. 1.0
  11.  - 1st release
  12. 1.1
  13.  - I have added a routine for reading characters and specify the read length
  14.    (BOX_getchrs)
  15. 1.2
  16.  - Added a Function to read single characters in a BBS.library like manner (BBS.library 
  17.    belongs to the AmBoS BBS)
  18.    (BOX_wgetchr)
  19.  - Fixed a bug in the Event-Handling: the Handler was called every time - if the signals
  20.    were set or not..   
  21.  - Improved the Documentation of the Headerfile
  22.  
  23. I have written it for all BBS-Door programmers (me included).
  24.  
  25. It should be very useful if one wants to input characters (a string) and react
  26. on events in parallel. This is important for MultiUserDungeons (MUD) and 
  27. related things.. I used on in a not_really_MUD named Gore. Its more a 
  28. MUDSG .. multiuserdungeonspladdergame.. 
  29.  
  30. Well.. it is not very funny if you are typing in a command, and when you are done 
  31. with it getting a message "a level 4711 Zombie has shaved you with a chainsaw" :))
  32.  
  33. An other Thing is the metacharacterexpander (what a word ..) 
  34. a "#" is used as a control character. the following character tells what happens:
  35. 0 -> color black
  36. 1 -> color red
  37. 2 -> color green
  38. 3 -> color blue
  39. 4 -> color yellow
  40. 5 -> color magenta
  41. 6 -> color cyan
  42. 7 -> color white
  43. n -> CR/LF
  44. s -> standard colors
  45.  
  46. These packetio-routines were originally not a shared lib, but we wanted to use the
  47. thing in a chatter-library (which will be soon available for AmBoS) and so
  48. the door_io.library was born :)
  49.  
  50. The library and all associated stuff is copyright by A.Haarer 1995+ and it
  51. may be freely used. It may be copied and spread on a non-profit basis.
  52. Commercial use is prohibited without written permission by Author .. ME !! :-)
  53.  
  54. Hum.. btw this program is thingware.. you may send anything to anyone :)
  55.  
  56. _______________________________________________________________________________
  57. Q: What is it for ??? 
  58.  
  59. A: Its a shared library that simplifies i/o operations in BBS-Cli-Doorprograms
  60.    - You are able to wait for Keys AND incoming exec-messages in parallel !
  61.    - You are able to specify a "carrier-lost-hook" to do cleanup when the line
  62.      breaks down
  63.    - it contains a metacharexpander which can generate colored output strings.
  64. ________________________________________________________________________________
  65. Q: How does it work ? 
  66.  
  67. A: The library does it's i/o operations by dospackets and therefore can wait()
  68.    for an input and other applicationspecific messages. The standard input() and
  69.    output() handles are used to determine the handler process.
  70. _________________________________________________________________________________
  71. Q: Why should i use it ? I can also poll the input stream  !
  72.  
  73. A: - Because polling in a multitasking environment ist complete bullshit ;-))
  74.    - Polling does slow down the whole system and is bad design, if other solutions
  75.      are possible.
  76.    - If you are polling single characters, you have to build a string input yourself.
  77.    - polling suxx :)
  78. _________________________________________________________________________________
  79. Q: How do i use it ?
  80.  
  81. A: - Replace your string input function by BOX_getstr()
  82.  
  83.    - Replace your string output function by BOX_getstr() and format the strings
  84.      with sprintf() when required.
  85.  
  86.    - Initialize the opened Library with BOX_start() and supply some parameters
  87.       - meta_on           1 -> the "#" controls the colors of text output
  88.                           0 -> the text output is not changed
  89.       - carrier_lost_hook (optional) is called when the handler returns an error
  90.                           (this is standard in most common bbs programs)
  91.       - exthandler        is called when one of the specified sigbits is set  
  92.       - sigmask           sigmask to trigger the exthandler
  93.  
  94.    - modify the signal mask by BOX_setmask() when required
  95.  
  96.    - Your carrier_lost_hook function should call BOX_stop() and close all resources of
  97.      your program
  98.  
  99.    - YOU MUST DECLARE BOTH HOOKFUNCTIONS with __saveds OR EQUIVALENT !
  100.      (__saveds restores the near data pointer, for some compilers its __geta4)
  101.  
  102.    - Call BOX_stop() when your program quits
  103. _________________________________________________________________________________
  104. Q: How contact the Author ? 
  105.  
  106. A: - Email to MAC@nasus.ohz.north.de or MAC@gorehost.dontpanic.sub.org
  107.    - Call the Castle of Confusion BBS : +49 421 636 7544 or +49 421 636 8643
  108.